/*
 * Copyright 2002-2007 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.context;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;

/**
 * #Comment#:扩展与ApplicationContext，新增了两个主要方法：refresh和close，
 * 让ApplicationContext具有启动、刷新和关闭应用上下文的能力。
 * <p>
 * SPI interface to be implemented by most if not all application contexts.
 * Provides facilities to configure an application context in addition to the
 * application context client methods in the
 * {@link org.springframework.context.ApplicationContext} interface.
 * 
 * <p>
 * Configuration and lifecycle methods are encapsulated here to avoid making
 * them obvious to ApplicationContext client code. The present methods should
 * only be used by startup and shutdown code.
 * 
 * @author Juergen Hoeller
 * @since 03.11.2003
 */
public interface ConfigurableApplicationContext extends ApplicationContext,
		Lifecycle {

	/**
	 * Set the parent of this application context.
	 * <p>
	 * Note that the parent shouldn't be changed: It should only be set outside
	 * a constructor if it isn't available when an object of this class is
	 * created, for example in case of WebApplicationContext setup.
	 * 
	 * @param parent
	 *            the parent context
	 * @see org.springframework.web.context.ConfigurableWebApplicationContext
	 */
	void setParent(ApplicationContext parent);

	/**
	 * Add a new BeanFactoryPostProcessor that will get applied to the internal
	 * bean factory of this application context on refresh, before any of the
	 * bean definitions get evaluated. To be invoked during context
	 * configuration.
	 * 
	 * @param beanFactoryPostProcessor
	 *            the factory processor to register
	 */
	void addBeanFactoryPostProcessor(
			BeanFactoryPostProcessor beanFactoryPostProcessor);

	/**
	 * Add a new ApplicationListener that will be notified on context events
	 * such as context refresh and context shutdown.
	 * <p>
	 * Note that any ApplicationListener registered here will be applied on
	 * refresh of this context. If a listener is added after the initial
	 * refresh, it will be applied on next refresh of the context.
	 * 
	 * @param listener
	 *            the ApplicationListener to register
	 * @see org.springframework.context.event.ContextRefreshedEvent
	 * @see org.springframework.context.event.ContextClosedEvent
	 */
	void addApplicationListener(ApplicationListener listener);

	/**
	 * Load or refresh the persistent representation of the configuration, which
	 * might an XML file, properties file, or relational database schema.
	 * <p>
	 * As this is a startup method, it should destroy already created singletons
	 * if it fails, to avoid dangling resources. In other words, after
	 * invocation of that method, either all or no singletons at all should be
	 * instantiated.
	 * 
	 * @throws BeansException
	 *             if the bean factory could not be initialized
	 * @throws IllegalStateException
	 *             if already initialized and multiple refresh attempts are not
	 *             supported
	 */
	void refresh() throws BeansException, IllegalStateException;

	/**
	 * Register a shutdown hook with the JVM runtime, closing this context on
	 * JVM shutdown unless it has already been closed at that time.
	 * <p>
	 * This method can be called multiple times. Only one shutdown hook (at max)
	 * will be registered for each context instance.
	 * 
	 * @see java.lang.Runtime#addShutdownHook
	 * @see #close()
	 */
	void registerShutdownHook();

	/**
	 * Close this application context, releasing all resources and locks that
	 * the implementation might hold. This includes destroying all cached
	 * singleton beans.
	 * <p>
	 * Note: Does <i>not</i> invoke <code>close</code> on a parent context;
	 * parent contexts have their own, independent lifecycle.
	 * <p>
	 * This method can be called multiple times without side effects: Subsequent
	 * <code>close</code> calls on an already closed context will be ignored.
	 */
	void close();

	/**
	 * Determine whether this application context is active, that is, whether it
	 * has been refreshed at least once and has not been closed yet.
	 * 
	 * @return whether the context is still active
	 * @see #refresh()
	 * @see #close()
	 * @see #getBeanFactory()
	 */
	boolean isActive();

	/**
	 * Return the internal bean factory of this application context. Can be used
	 * to access specific functionality of the underlying factory.
	 * <p>
	 * Note: Do not use this to post-process the bean factory; singletons will
	 * already have been instantiated before. Use a BeanFactoryPostProcessor to
	 * intercept the BeanFactory setup process before beans get touched.
	 * <p>
	 * Generally, this internal factory will only be accessible while the
	 * context is active, that is, inbetween {@link #refresh()} and
	 * {@link #close()}. The {@link #isActive()} flag can be used to check
	 * whether the context is in an appropriate state.
	 * 
	 * @return the underlying bean factory
	 * @throws IllegalStateException
	 *             if the context does not hold an internal bean factory
	 *             (usually if {@link #refresh()} hasn't been called yet or if
	 *             {@link #close()} has already been called)
	 * @see #isActive()
	 * @see #refresh()
	 * @see #close()
	 * @see #addBeanFactoryPostProcessor
	 */
	ConfigurableListableBeanFactory getBeanFactory()
			throws IllegalStateException;

}
